home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / include / linux / scatterlist.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-12-24  |  7.6 KB  |  266 lines
  1. #ifndef _LINUX_SCATTERLIST_H
  2. #define _LINUX_SCATTERLIST_H
  3.  
  4. #include <asm/types.h>
  5. #include <asm/scatterlist.h>
  6. #include <linux/mm.h>
  7. #include <linux/string.h>
  8. #include <asm/io.h>
  9.  
  10. struct sg_table {
  11.     struct scatterlist *sgl;    /* the list */
  12.     unsigned int nents;        /* number of mapped entries */
  13.     unsigned int orig_nents;    /* original size of list */
  14. };
  15.  
  16. /*
  17.  * Notes on SG table design.
  18.  *
  19.  * Architectures must provide an unsigned long page_link field in the
  20.  * scatterlist struct. We use that to place the page pointer AND encode
  21.  * information about the sg table as well. The two lower bits are reserved
  22.  * for this information.
  23.  *
  24.  * If bit 0 is set, then the page_link contains a pointer to the next sg
  25.  * table list. Otherwise the next entry is at sg + 1.
  26.  *
  27.  * If bit 1 is set, then this sg entry is the last element in a list.
  28.  *
  29.  * See sg_next().
  30.  *
  31.  */
  32.  
  33. #define SG_MAGIC    0x87654321
  34.  
  35. /*
  36.  * We overload the LSB of the page pointer to indicate whether it's
  37.  * a valid sg entry, or whether it points to the start of a new scatterlist.
  38.  * Those low bits are there for everyone! (thanks mason :-)
  39.  */
  40. #define sg_is_chain(sg)        ((sg)->page_link & 0x01)
  41. #define sg_is_last(sg)        ((sg)->page_link & 0x02)
  42. #define sg_chain_ptr(sg)    \
  43.     ((struct scatterlist *) ((sg)->page_link & ~0x03))
  44.  
  45. /**
  46.  * sg_assign_page - Assign a given page to an SG entry
  47.  * @sg:            SG entry
  48.  * @page:        The page
  49.  *
  50.  * Description:
  51.  *   Assign page to sg entry. Also see sg_set_page(), the most commonly used
  52.  *   variant.
  53.  *
  54.  **/
  55. static inline void sg_assign_page(struct scatterlist *sg, struct page *page)
  56. {
  57.     unsigned long page_link = sg->page_link & 0x3;
  58.  
  59.     /*
  60.      * In order for the low bit stealing approach to work, pages
  61.      * must be aligned at a 32-bit boundary as a minimum.
  62.      */
  63.     BUG_ON((unsigned long) page & 0x03);
  64. #ifdef CONFIG_DEBUG_SG
  65.     BUG_ON(sg->sg_magic != SG_MAGIC);
  66.     BUG_ON(sg_is_chain(sg));
  67. #endif
  68.     sg->page_link = page_link | (unsigned long) page;
  69. }
  70.  
  71. /**
  72.  * sg_set_page - Set sg entry to point at given page
  73.  * @sg:         SG entry
  74.  * @page:     The page
  75.  * @len:     Length of data
  76.  * @offset:     Offset into page
  77.  *
  78.  * Description:
  79.  *   Use this function to set an sg entry pointing at a page, never assign
  80.  *   the page directly. We encode sg table information in the lower bits
  81.  *   of the page pointer. See sg_page() for looking up the page belonging
  82.  *   to an sg entry.
  83.  *
  84.  **/
  85. static inline void sg_set_page(struct scatterlist *sg, struct page *page,
  86.                    unsigned int len, unsigned int offset)
  87. {
  88.     sg_assign_page(sg, page);
  89.     sg->offset = offset;
  90.     sg->length = len;
  91. }
  92.  
  93. static inline struct page *sg_page(struct scatterlist *sg)
  94. {
  95. #ifdef CONFIG_DEBUG_SG
  96.     BUG_ON(sg->sg_magic != SG_MAGIC);
  97.     BUG_ON(sg_is_chain(sg));
  98. #endif
  99.     return (struct page *)((sg)->page_link & ~0x3);
  100. }
  101.  
  102. /**
  103.  * sg_set_buf - Set sg entry to point at given data
  104.  * @sg:         SG entry
  105.  * @buf:     Data
  106.  * @buflen:     Data length
  107.  *
  108.  **/
  109. static inline void sg_set_buf(struct scatterlist *sg, const void *buf,
  110.                   unsigned int buflen)
  111. {
  112.     sg_set_page(sg, virt_to_page(buf), buflen, offset_in_page(buf));
  113. }
  114.  
  115. /*
  116.  * Loop over each sg element, following the pointer to a new list if necessary
  117.  */
  118. #define for_each_sg(sglist, sg, nr, __i)    \
  119.     for (__i = 0, sg = (sglist); __i < (nr); __i++, sg = sg_next(sg))
  120.  
  121. /**
  122.  * sg_chain - Chain two sglists together
  123.  * @prv:    First scatterlist
  124.  * @prv_nents:    Number of entries in prv
  125.  * @sgl:    Second scatterlist
  126.  *
  127.  * Description:
  128.  *   Links @prv@ and @sgl@ together, to form a longer scatterlist.
  129.  *
  130.  **/
  131. static inline void sg_chain(struct scatterlist *prv, unsigned int prv_nents,
  132.                 struct scatterlist *sgl)
  133. {
  134. #ifndef ARCH_HAS_SG_CHAIN
  135.     BUG();
  136. #endif
  137.  
  138.     /*
  139.      * offset and length are unused for chain entry.  Clear them.
  140.      */
  141.     prv[prv_nents - 1].offset = 0;
  142.     prv[prv_nents - 1].length = 0;
  143.  
  144.     /*
  145.      * Set lowest bit to indicate a link pointer, and make sure to clear
  146.      * the termination bit if it happens to be set.
  147.      */
  148.     prv[prv_nents - 1].page_link = ((unsigned long) sgl | 0x01) & ~0x02;
  149. }
  150.  
  151. /**
  152.  * sg_mark_end - Mark the end of the scatterlist
  153.  * @sg:         SG entryScatterlist
  154.  *
  155.  * Description:
  156.  *   Marks the passed in sg entry as the termination point for the sg
  157.  *   table. A call to sg_next() on this entry will return NULL.
  158.  *
  159.  **/
  160. static inline void sg_mark_end(struct scatterlist *sg)
  161. {
  162. #ifdef CONFIG_DEBUG_SG
  163.     BUG_ON(sg->sg_magic != SG_MAGIC);
  164. #endif
  165.     /*
  166.      * Set termination bit, clear potential chain bit
  167.      */
  168.     sg->page_link |= 0x02;
  169.     sg->page_link &= ~0x01;
  170. }
  171.  
  172. /**
  173.  * sg_phys - Return physical address of an sg entry
  174.  * @sg:         SG entry
  175.  *
  176.  * Description:
  177.  *   This calls page_to_phys() on the page in this sg entry, and adds the
  178.  *   sg offset. The caller must know that it is legal to call page_to_phys()
  179.  *   on the sg page.
  180.  *
  181.  **/
  182. static inline dma_addr_t sg_phys(struct scatterlist *sg)
  183. {
  184.     return page_to_phys(sg_page(sg)) + sg->offset;
  185. }
  186.  
  187. /**
  188.  * sg_virt - Return virtual address of an sg entry
  189.  * @sg:      SG entry
  190.  *
  191.  * Description:
  192.  *   This calls page_address() on the page in this sg entry, and adds the
  193.  *   sg offset. The caller must know that the sg page has a valid virtual
  194.  *   mapping.
  195.  *
  196.  **/
  197. static inline void *sg_virt(struct scatterlist *sg)
  198. {
  199.     return page_address(sg_page(sg)) + sg->offset;
  200. }
  201.  
  202. struct scatterlist *sg_next(struct scatterlist *);
  203. struct scatterlist *sg_last(struct scatterlist *s, unsigned int);
  204. void sg_init_table(struct scatterlist *, unsigned int);
  205. void sg_init_one(struct scatterlist *, const void *, unsigned int);
  206.  
  207. typedef struct scatterlist *(sg_alloc_fn)(unsigned int, gfp_t);
  208. typedef void (sg_free_fn)(struct scatterlist *, unsigned int);
  209.  
  210. void __sg_free_table(struct sg_table *, unsigned int, sg_free_fn *);
  211. void sg_free_table(struct sg_table *);
  212. int __sg_alloc_table(struct sg_table *, unsigned int, unsigned int, gfp_t,
  213.              sg_alloc_fn *);
  214. int sg_alloc_table(struct sg_table *, unsigned int, gfp_t);
  215.  
  216. size_t sg_copy_from_buffer(struct scatterlist *sgl, unsigned int nents,
  217.                void *buf, size_t buflen);
  218. size_t sg_copy_to_buffer(struct scatterlist *sgl, unsigned int nents,
  219.              void *buf, size_t buflen);
  220.  
  221. /*
  222.  * Maximum number of entries that will be allocated in one piece, if
  223.  * a list larger than this is required then chaining will be utilized.
  224.  */
  225. #define SG_MAX_SINGLE_ALLOC        (PAGE_SIZE / sizeof(struct scatterlist))
  226.  
  227.  
  228. /*
  229.  * Mapping sg iterator
  230.  *
  231.  * Iterates over sg entries mapping page-by-page.  On each successful
  232.  * iteration, @miter->page points to the mapped page and
  233.  * @miter->length bytes of data can be accessed at @miter->addr.  As
  234.  * long as an interation is enclosed between start and stop, the user
  235.  * is free to choose control structure and when to stop.
  236.  *
  237.  * @miter->consumed is set to @miter->length on each iteration.  It
  238.  * can be adjusted if the user can't consume all the bytes in one go.
  239.  * Also, a stopped iteration can be resumed by calling next on it.
  240.  * This is useful when iteration needs to release all resources and
  241.  * continue later (e.g. at the next interrupt).
  242.  */
  243.  
  244. #define SG_MITER_ATOMIC        (1 << 0)     /* use kmap_atomic */
  245.  
  246. struct sg_mapping_iter {
  247.     /* the following three fields can be accessed directly */
  248.     struct page        *page;        /* currently mapped page */
  249.     void            *addr;        /* pointer to the mapped area */
  250.     size_t            length;        /* length of the mapped area */
  251.     size_t            consumed;    /* number of consumed bytes */
  252.  
  253.     /* these are internal states, keep away */
  254.     struct scatterlist    *__sg;        /* current entry */
  255.     unsigned int        __nents;    /* nr of remaining entries */
  256.     unsigned int        __offset;    /* offset within sg */
  257.     unsigned int        __flags;
  258. };
  259.  
  260. void sg_miter_start(struct sg_mapping_iter *miter, struct scatterlist *sgl,
  261.             unsigned int nents, unsigned int flags);
  262. bool sg_miter_next(struct sg_mapping_iter *miter);
  263. void sg_miter_stop(struct sg_mapping_iter *miter);
  264.  
  265. #endif /* _LINUX_SCATTERLIST_H */
  266.